clsx

What is clsx?

The clsx package is a tiny utility for constructing className strings conditionally. It is also a faster & smaller drop-in replacement for the 'classnames' library.

What are clsx's main functionalities?

Conditional class string construction

This feature allows you to construct a class string with conditional classes. If the condition is true, the class is included; otherwise, it is excluded. In the code sample, 'baz' will be included in the output string, while 'qux-quux' will not, resulting in 'foo bar baz'.

clsx('foo', 'bar', { 'baz': true, 'qux-quux': false })

Combining class strings

clsx can combine multiple class strings and arrays of class strings, ignoring falsy values. In the code sample, the output would be 'foo bar baz qux'.

clsx('foo', null, ['bar', 'baz'], { 'qux': true })

Handling arrays and nested arrays

clsx can handle arrays and nested arrays of class names with conditional logic. In the code sample, the output would be 'foo bar baz' as the nested array and object are properly evaluated.

clsx(['foo', ['bar', { 'baz': true }]])

Other packages similar to clsx

classnames

The 'classnames' package is the original utility that clsx was designed to replace. It offers similar functionality for conditionally joining classNames together. clsx claims to be a faster and smaller alternative to 'classnames'.

emotion

The 'emotion' package is a performant and flexible CSS-in-JS library. While it is more feature-rich, offering styled components and dynamic styling, it also includes the 'cx' function which is similar to clsx for combining class names conditionally.

README

clsx

A tiny (239B) utility for constructing className strings conditionally.
Also serves as a faster & smaller drop-in replacement for the classnames module.

This module is available in three formats:

• ES Module: dist/clsx.mjs
• CommonJS: dist/clsx.js
• UMD: dist/clsx.min.js

Install

$ npm install --save clsx

Usage

import clsx from 'clsx';
// or
import { clsx } from 'clsx';

// Strings (variadic)
clsx('foo', true && 'bar', 'baz');
//=> 'foo bar baz'

// Objects
clsx({ foo:true, bar:false, baz:isTrue() });
//=> 'foo baz'

// Objects (variadic)
clsx({ foo:true }, { bar:false }, null, { '--foobar':'hello' });
//=> 'foo --foobar'

// Arrays
clsx(['foo', 0, false, 'bar']);
//=> 'foo bar'

// Arrays (variadic)
clsx(['foo'], ['', 0, false, 'bar'], [['baz', [['hello'], 'there']]]);
//=> 'foo bar baz hello there'

// Kitchen sink (with nesting)
clsx('foo', [1 && 'bar', { baz:false, bat:null }, ['hello', ['world']]], 'cya');
//=> 'foo bar hello world cya'

API

clsx(...input)

Returns: String

input

Type: Mixed

The clsx function can take any number of arguments, each of which can be an Object, Array, Boolean, or String.

Important: Any falsey values are discarded!
Standalone Boolean values are discarded as well.

clsx(true, false, '', null, undefined, 0, NaN);
//=> ''

Modes

There are multiple "versions" of clsx available, which allows you to bring only the functionality you need!

clsx

Size (gzip): 239 bytes
Availability: CommonJS, ES Module, UMD

The default clsx module; see API for info.

import { clsx } from 'clsx';
// or
import clsx from 'clsx';

clsx/lite

Size (gzip): 140 bytes
Availability: CommonJS, ES Module
CAUTION: Accepts ONLY string arguments!

Ideal for applications that only use the string-builder pattern.

Any non-string arguments are ignored!

import { clsx } from 'clsx/lite';
// or
import clsx from 'clsx/lite';

// string
clsx('hello', true && 'foo', false && 'bar');
// => "hello foo"

// NOTE: Any non-string input(s) ignored
clsx({ foo: true });
//=> ""

Benchmarks

For snapshots of cross-browser results, check out the bench directory~!

Support

All versions of Node.js are supported.

All browsers that support Array.isArray are supported (IE9+).

Note: For IE8 support and older, please install clsx@1.0.x and beware of #17.

Tailwind Support

Here some additional (optional) steps to enable classes autocompletion using clsx with Tailwind CSS.

Visual Studio Code

1. Install the "Tailwind CSS IntelliSense" Visual Studio Code extension

2. Add the following to your settings.json:

 {
  "tailwindCSS.experimental.classRegex": [
    ["clsx\\(([^)]*)\\)", "(?:'|\"|`)([^']*)(?:'|\"|`)"]
  ]
 }

You may find the clsx/lite module useful within Tailwind contexts. This is especially true if/when your application only composes classes in this pattern:

clsx('text-base', props.active && 'text-primary', props.className);

Related

• obj-str - A smaller (96B) and similiar utility that only works with Objects.

License

MIT © Luke Edwards